Skip Headers

Oracle® Text Reference 10g Release 2 (10.2) Part Number B14218-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 6 CTX_CLS Package

This chapter provides reference information for using the `CTX_CLS` PL/SQL package. This package enables you to perform document classification.

See Also: The Oracle Text Application Developer's Guide for more on document classification

Name | Description
--- | ---
TRAIN | Generates rules that define document categories. Output based on input training document set.
CLUSTERING | Generates clusters for a document collection.

## TRAIN

Use this procedure to generate query rules that select document categories. You must supply a training set consisting of categorized documents. Documents can be in any format supported by Oracle Text and must belong to one or more categories. This procedure generates the queries that define the categories and then writes the results to a table.

You must also have a document table and a category table. The category table must contain at least two categories.

For example, your document and category tables can be defined as:

    create table trainingdoc(

    docid number primary key,
    text varchar2(4000));

    create table category (

    docid trainingdoc(docid),
    categoryid number);

You can use one of two syntaxes depending on the classification algorithm you need. The query compatible syntax uses the `RULE_CLASSIFIER` preference and generates rules as query strings. The support vector machine syntax uses the `SVM_CLASSIFER` preference and generates rules in binary format. The `SVM_CLASSIFIER` is good for high classification accuracy, but because its rules are generated in binary format, they cannot be examined like the query strings generated with the `RULE_CLASSIFIER`. Note that only those document ids that appear in both the document table and the category table will impact `RULE_CLASSIFIER` and `SVM_CLASSIFIER` learning.

The `CTX_CLS.TRAIN` procedure requires that your document table have an associated context index. For best results, the index should be synchronized before running this procedure. `SVM_CLASSIFIER` syntax enables the use of an unpopulated context index, while query-compatible syntax requires that the context index be populated.

See Also: The Oracle Text Application Developer's Guide for more on document classification.

Query Compatible Syntax

The following syntax generates query-compatible rules and is used with the RULE_CLASSIFIER preference. Use this syntax and preference when different categories are separated from others by several key words. An advantage of generating your rules as query strings is that you can easily examine the generated rules. This is different from generating SVM rules, which are in binary format.

    CTX_CLS.TRAIN(

    index_name    in varchar2,
    docid         in varchar2,
    cattab        in varchar2,
    catdocid      in varchar2,
    catid         in varchar2,
    restab        in varchar2,
    rescatid      in varchar2,
    resquery      in varchar2,
    resconfid     in varchar2,
    preference    in varchar2 DEFAULT NULL

    );

index_name

  Specify the name of the context index associated with your document training set.

docid

  Specify the name of the document id column in the document table. This column must contain unique document ids. This column must a NUMBER.

cattab

  Specify the name of the category table. You must have SELECT privilege on this table.

catdocid

  Specify the name of the document id column in the category table. The document ids in this table must also exist in the document table. This column must a NUMBER.

catid

  Specify the name of the category ID column in the category table. This column must a NUMBER.

restab

  Specify the name of the result table. You must have INSERT privilege on this table.

rescatid

  Specify the name of the category ID column in the result table. This column must a NUMBER.

resquery

  Specify the name of the query column in the result table. This column must be VARACHAR2, CHAR CLOB, NVARCHAR2, or NCHAR.

  The queries generated in this column connects terms with AND or NOT operators, such as:

  'T1 & T2 ~ T3'

  Terms can also be theme tokens and be connected with the ABOUT operator, such as:

  'about(T1) & about(T2) ~ about(T3)'

  Generated rules also support WITHIN queries on field sections.

resconfid

  Specify the name of the confidence column in result table. This column contains the estimated probability from training data that a document is relevant if that document satisfies the query.

preference

  Specify the name of the preference. For classifier types and attributes, see "Classifier Types" in Chapter 2, " Oracle Text Indexing Elements".

Syntax for Support Vector Machine Rules

The following syntax generates support vector machine (SVM) rules with the SVM_CLASSIFIER preference. This preference generates rules in binary format. Use this syntax when your application requires high classification accuracy.

    CTX_CLS.TRAIN(
        index_name in varchar2,
        docid      in varchar2,
        cattab     in varchar2,
        catdocid   in varchar2,
        catid      in varchar2,
        restab     in varchar2,
        preference in varchar2 );

index_name

  Specify the name of the text index.

docid

  Specify the name of docid column in document table.

cattab

  Specify the name of category table.

catdocid

  Specify the name of docid column in category table.

catid

  Specify the name of category ID column in category table.

restab

  Specify the name of result table.

  The result table has the following format:

  Column Name | Datatype | Description
  --- | --- | ---
  `CAT_ID` | NUMBER | The ID of the category.
  `TYPE` | NUMBER(3) NOT NULL | 0 for the actual rule or catid; 1 for other.
  `RULE` | BLOB | The returned rule.

preference

  Specify the name of user preference. For classifier types and attributes, see "Classifier Types" in Chapter 2, " Oracle Text Indexing Elements".

Example

The `CTX_CLS.TRAIN` procedure is used in supervised classification. For an extended example, see the Oracle Text Application Developer's Guide.

## CLUSTERING

Use this procedure to cluster a collection of documents. A cluster is a group of documents similar to each other in content.

A clustering result set is composed of document assignments and cluster descriptions:

- A document assignment result set shows how relevant each document is to all generated leaf clusters.

- A cluster description result set contains information about what topic a cluster is about. This result set identifies the cluster and contains cluster description text, a suggested cluster label, and a quality score for the cluster.

Cluster output is hierarchical. Only leaf clusters are scored for relevance to documents. Producing more clusters requires more computing time. You indicate the upper limit for generated clusters with the `CLUSTER_NUM` attribute of the `KMEAN_CLUSTERING` cluster type (see "Cluster Types").

There are two versions of this procedure: one with a table result set, and one with an in-memory result set.

Clustering is also known as unsupervised classification.

See Also: For more information about clustering, see "Cluster Types" in Chapter 2, " Oracle Text Indexing Elements", which contains relevant preferences, as well as the Oracle Text Application Developer's Guide.

Syntax: Table Result Set

    ctx_cls.clustering (
     index_name  IN VARCHAR2,
     docid       IN VARCHAR2,
     doctab_name IN VARCHAR2,
     clstab_name IN VARCHAR2,
     pref_name   IN VARCHAR2  DEFAULT NULL
    );

index_name

  Specify the name of the context index on collection table.

docid

  Specify the name of document ID column of the collection table.

doctab_name

  Specify the name of document assignment table. This procedure creates the table with the following structure:

      doc_assign(
         docid number,
         clusterid number,
         score number
      );

  Column | Description
  --- | ---
  DOCID | Document ID to identify document.
  CLUSTERID | ID of a leaf cluster associated with this document. If `CLUSTERID` is -1, then the cluster contains "miscellaneous" documents; for example, documents that cannot be assigned to any other cluster category.
  SCORE | The associated score between the document and the cluster.

  If you require more columns, you can create the table before you call this procedure.

clstab_name

  Specify the name of the cluster description table. This procedure creates the table with the following structure:

      cluster_desc(
        clusterid NUMBER,
        descript VARCHAR2(4000),
        label VARCHAR2(200),
        sze NUMBER,
        quality_score NUMBER,
        parent NUMBER
      );

  Column | Description
  --- | ---
  CLUSTERID | Cluster ID to identify cluster. If CLUSTERID is -1, then the cluster contains "miscellaneous" documents; for example, documents that cannot be assigned to any other cluster category.
  DESCRIPT | String to describe the cluster.
  LABEL | A suggested label for the cluster.
  SZE | This parameter currently has no value.
  QUALITY_SCORE | The quality score of the cluster. A higher number indicates greater coherence.
  PARENT | The parent cluster id. Zero means no parent cluster.

  If you require more columns, you can create the table before you call this procedure.

pref_name

  Specify the name of the preference.

Syntax: In-Memory Result Set

You can put the result set into in-memory structures for better performance. Two in-memory tables are defined in CTX_CLS package for document assignment and cluster description respectively.

    CTX_CLS.CLUSTERING(
      index_name     IN VARCHAR2,
      docid          IN VARCHAR2,
      dids           IN DOCID_TAB,
      doctab_name    IN OUT NOCOPY DOC_TAB,
      clstab_name    IN OUT NOCOPY CLUSTER_TAB,
      pref_name      IN VARCHAR2  DEFAULT NULL
              );

index_name

  Specify the name of context index on the collection table.

docid

  Specify the document id column of the collection table.

dids

  Specify the name of the in-memory docid_tab.

      TYPE docid_tab IS TABLE OF number INDEX BY BINARY_INTEGER;

doctab_name

  Specify name of the document assignment in-memory table. This table is defined as follows:

      TYPE doc_rec IS RECORD (
         docid NUMBER,
         clusterid NUMBER,
         score NUMBER
      )
      TYPE doc_tab IS TABLE OF doc_rec INDEX BY BINARY_INTEGER;

  Column | Description
  --- | ---
  DOCID | Document ID to identify document.
  CLUSTERID | ID of a leaf cluster associated with this document. If `CLUSTERID` is -1, then the cluster contains "miscellaneous" documents; for example, documents that cannot be assigned to any other cluster category.
  SCORE | The associated score between the document and the cluster.

cls_tab

  Specify the name of cluster description in-memory table

      TYPE cluster_rec IS RECORD(
           clusterid NUMBER,
           descript VARCHAR2(4000),
           label VARCHAR2(200),
           sze NUMBER,
           quality_score NUMBER,
           parent NUMBER
      );
      TYPE cluster_tab IS TABLE OF cluster_rec INDEX BY BINARY_INTEGER;

  Column | Description
  --- | ---
  CLUSTERID | Cluster ID to identify cluster. If CLUSTERID is -1, then the cluster contains "miscellaneous" documents; for example, documents that cannot be assigned to any other cluster category.
  DESCRIPT | String to describe the cluster.
  LABEL | A suggested label for the cluster.
  SZE | This parameter currently has no value.
  QUALITY_SCORE | The quality score of the cluster. A higher number indicates greater coherence.
  PARENT | The parent cluster id. Zero means no parent cluster.

pref_name

  Specify the name of the preference. For cluster types and attributes, see "Cluster Types" in Chapter 2, " Oracle Text Indexing Elements".

Example

See Also: The Oracle Text Application Developer's Guide for an example of using clustering.